home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d923.lha / OberonPrefs / OberonPrefs.doc < prev    next >
Text File  |  1993-10-07  |  36KB  |  853 lines
  1.  
  2.             --------------------------------------------------
  3.             OberonPrefs 1.11d (20.9.93) © F.Schwarz - Giftware
  4.             --------------------------------------------------
  5.  
  6.                     Preferences editor for Amiga-Oberon
  7.  
  8.                             Written & © 1993 by
  9.                                Franz Schwarz
  10.                               Mühlenstraße 2
  11.                        D-78591 Durchhausen, Germany
  12.                     Uucp: Franz_Schwarz@mil.ka.sub.org
  13.                     Fido: 2:2476/506.18 & 2:241/7506.18
  14.  
  15.              GUI created with assistance of GadToolsBox 37.176
  16.  
  17.          Since OberonPrefs is Giftware you are encouraged to send
  18.        the author a present, money, a postcard, etc. if you use it.
  19.  
  20.  
  21.  
  22.                              table of contents
  23.                              -----------------
  24.  
  25.                          concepts, program design
  26.  
  27.                     contents of the authorized archive
  28.  
  29.                         the installation procedure
  30.  
  31.                   the interacive graphical user interface
  32.                     -gadgets
  33.                     -menus
  34.                     -dragging icons into the window
  35.                     
  36.                     commandline and ToolTypes arguments
  37.                       -the argument stencil
  38.                       -discussion of each argument
  39.                       -user definable interactive argument
  40.                        request when started from Workbench
  41.                        
  42.                     program termination & return codes
  43.                   
  44.                      general issues about the program
  45.  
  46.                    how to avoid source code modification
  47.  
  48.                               program history
  49.                               
  50.                                 final notes
  51.  
  52.                            contacting the author
  53.  
  54.                                   credits
  55.                                   
  56.                         the CygnusEd Arexx scripts
  57.                                   
  58.  
  59.                          concepts, program design
  60.                          ------------------------
  61.  
  62. OberonPrefs is the very program for your Oberon system that you've missed
  63. all the time - until now!;-) It's a very flexible, universal, intuitive,
  64. highly user-configurable preferences editor for Oberon's compiler/linker
  65. options that offers both, a comfortable graphical user interface and a
  66. well-designed shell interface (which may be completely accessed via
  67. icon ToolTypes, by the way).  Furthermore it adapts to the user's locale
  68. -i.e. it uses your prefered tongue and meassure output characteristics-
  69. if you run Workbench 2.1 or higher.
  70.  
  71.  
  72. A brief summary on how Amiga Oberon gains the compiler / linker options:
  73.  
  74.   Firstly, the hardcoded internal default options of the Oberon system are
  75.   considered.
  76.   
  77.   These options are overridden by the options you specify in the commandline
  78.   (or by the ToolTypes of the invoked tool on Workbench start)
  79.   
  80.   Afterwards, options from the option preferences files Oberon.prefs and
  81.   OLink.prefs in the directory of the processed project are taken into
  82.   account (and overwrite any hitherto read options!)
  83.   
  84.   Finally, if the respective preferences file Oberon.prefs / OLink.prefs
  85.   couldn't be found in the directory of the processed project and the
  86.   respective global Oberon.prefs / OLink.prefs exists in the OBERON:
  87.   directory, the options from this file are accounted.  Of course, these
  88.   options override any previously read options, too.
  89.  
  90.  
  91. In order to come up to the user's individual likes and configurations,
  92. OberonPrefs is highly user-configurable in terms of reading and writing the
  93. compiler / linker options.  This configuration can be set via a commandline
  94. / ToolTypes argument, a global settings file or via menus in the
  95. interactive mode.
  96.  
  97.  
  98. OberonPrefs basically has two different operation modes:  a global mode,
  99. where the global compiler / linker options are processed, and a project
  100. mode where the options for different projects and / or those for a single
  101. source code module are processed.  It is straight forward that the
  102. possiblity of mutual import / export between these modes exists.
  103.  
  104.  
  105. OberonPrefs provides you with the ability to manipulate all currently
  106. available compiler / linker options (as of Amiga Oberon 3.00) - for the
  107. project mode including those that may be only controled from within source
  108. code modules and whose scope is generally the whole source code module
  109. (CodeChip, VarsChip, DataChip, Implementation).
  110.  
  111.  
  112. As the user interfaces (interactive graphical user interface, commandline
  113. interface, Workbench ToolTypes interface) have been designed in a way that
  114. they usually comply with the guidelines for preferences editors stated in
  115. the 'Amiga User Interface Style Guide', the utilization and operation of
  116. OberonPrefs should be highly self-explaining and intuitive for the user who
  117. is familar with operating Amiga preferences editors (e.g.  those placed in
  118. the SYS:Prefs drawer of your boot disk).  However, the concept of two
  119. different operation modes (Global / Project), the versatile options in the
  120. Settings menu and the extension of the commandline / ToolTypes interface
  121. for your ease when dealing with ARexx scripts and batch files are beyond
  122. the ordinary prefs editors' features and deserve special attention.
  123.  
  124.  
  125.                     contents of the authorized archive
  126.                     ----------------------------------
  127.  
  128.      Catalogs (dir)
  129.           deutsch (dir)
  130.             blackmagic.catalog               oberonprefs.catalog
  131.      Libs (dir)
  132.        oberonsupport.library            reqtools.library
  133.      Locale (dir)
  134.        BlackMagic.cd                    BlackMagic.cd.info
  135.        BlackMagic_d.ct                  BlackMagic_d.ct.info
  136.        OberonPrefs.cd                   OberonPrefs.cd.info
  137.        OberonPrefs_d.ct                 OberonPrefs_d.ct.info
  138.      Rexx (dir)
  139.        OCmd.ced                         OCmd.ced.info
  140.        OErr.ced                         OErr.ced.info
  141.        OOptions.ced                     OOptions.ced.info
  142.      s (dir)
  143.        RexxCommands                     RexxCommands.info
  144.   Catalogs.info                    InstallOberonPrefs
  145.   InstallOberonPrefs.info          Libs.info
  146.   Locale.info                      OberonPrefs
  147.   OberonPrefs.doc                  OberonPrefs.doc.info
  148.   OberonPrefs.dok                  OberonPrefs.dok.info
  149.   OberonPrefs.info                 Rexx.info
  150.   s.info
  151.  
  152.  
  153.  
  154.                         the installation procedure
  155.                         --------------------------
  156.  
  157. The installation is automatically performed by the installation script.  It
  158. copies OberonPrefs and the documentation files into the OBERON:  directory
  159. and writes the catalogs into the LOCALE:  directory if Workbench 2.1 or
  160. higher is installed in your system.  In addition to this, the installation
  161. script can also install die CyngusEd Arexx scripts for running the Oberon
  162. system from within CygnusEd on your request.
  163.  
  164. It is recommended to add a 'resident OBERON:OberonPrefs' statement to your
  165. s:user-startup if you use OberonPrefs and / or the ARexx scripts frequently.
  166.  
  167.  
  168.                   the interacive graphical user interface
  169.                   ---------------------------------------
  170.  
  171.   -------
  172.   Gadgets
  173.   -------
  174.  
  175. Apart from the gadgets for the various compiler / linker options which are
  176. not described in this document since they are extensively discussed in the
  177. Amiga Oberon documentation, the following gadgets are available:
  178.  
  179. Mode gadget - controls the operation mode:
  180.   Global : for modifying the global compiler / linker options
  181.   Project: for modifying project / source code module specific options
  182.   *1*
  183.   
  184. Project Display gadget - displays the name of the currently selected source  
  185.   code module in Project operation mode. If the gadget name consists of a
  186.   character with an underscore, a keypress of that marked key selects the
  187.   File gadget.
  188.   
  189. File gadget - pops up a file requester where you may select a new project.
  190.   If you confirm the selection, OberonPrefs tries to open and validate the
  191.   project, sets the Project operation mode and reads the project's options
  192.   according to the settings in the Settings menu.
  193.   *1*
  194.   
  195. Save gadget - in case the Project operation mode is active and no
  196.   valid file name is known, a file requester pops up where you can
  197.   select a project for the options to save. If the project can't be
  198.   validated, no changes occure. Otherwise / afterwards the currently
  199.   active options are saved according to the settings in the Settings
  200.   menu _without_ quitting OberonPrefs (This was a design decision due
  201.   to the two operation modes and the possibility of manipulating
  202.   project settings).
  203.   However, if one of the commandline / ToolTypes arguments OBERONOUT, 
  204.   OLINKOUT or OMAKEOUT has been specified, OberonPrefs quits immediately
  205.   after saving because no change of the operation mode or the processed
  206.   project is possible in that case.
  207.   *2*
  208.   
  209. Cancel gadget - quits OberonPrefs without saving any previously made
  210.   changes.
  211.   *1*
  212.    
  213. Use gadget - quits OberonPrefs without saving any previously made changes, 
  214.   _but_ prints the selected options according to the specified #?OUT
  215.   argument to stdout.
  216.   *3*
  217.   
  218. Close gadget - corresponds to selecting the Cancel gadget. The key 
  219.   equivalent for this system gadget is the ESC key.
  220.   
  221. Zoom gadget - iconifies OberonPrefs' window or restores its original size,  
  222.   respectively. The key equivalent for this system gadget is the 'Z' key.
  223.   
  224.  
  225. All gadgets whose titles contain an underscored character may be selected
  226. by pressing the respective key, too.
  227.  
  228.  
  229.  
  230. *1* :  Is not available if one of the arguments OBERONOUT, OLINKOUT or
  231.        OMAKEOUT has been specified at the program start.
  232.        
  233. *2* :  Is not available if one of the arguments OBERONOUT, OLINKOUT or
  234.        OMAKEOUT plus the NOSAVEGAD switch has been specified at the 
  235.        program start.
  236.  
  237. *3* :  Is only available if one of the arguments OBERONOUT, OLINKOUT or
  238.        OMAKEOUT has been specified at the program start.
  239.  
  240.  
  241.  
  242.   -----
  243.   Menus
  244.   -----
  245.  
  246. Project menu:
  247.   
  248.   New - resets the options to the internal default options of Amiga-Oberon
  249.   and clears the project name if the Project operating mode is active
  250.  
  251.   Open... - this is equivalent to triggering the File gadget
  252.   
  253.   Save As... - opens a file requester, and, if the name of an existing
  254.   source code module is specified, enforces the Project operation mode
  255.   and saves the currently selected options as the source code module's
  256.   options.
  257.   *1*
  258.   
  259.   Save As Globals - enforces the Global operation mode and saves the
  260.   currently selected options as the global compiler / linker options.
  261.   *1*
  262.   
  263.   About... - this makes OberonPrefs pop a requester with some information
  264.     on OberonPrefs.
  265.       In the last line of the requester, the code for the currently
  266.       active settings in the Settings menu is displayed. This code may be
  267.       written to ENVARC:OberonPrefs.prefs or supplied as a SETTINGS/N/K
  268.       argument when starting OberonPrefs in order to retrieve the current
  269.       settings in the Settings menu.
  270.       *1*
  271.       
  272.   Quit - this menu item has the same effect as triggering the Cancel gadget.    
  273.   
  274. Edit menu:  
  275.  
  276.   Reset To Defaults - resets the options to the internal default options
  277.     of the Amiga Oberon system.
  278.     
  279.   Last Saved Globals - imports the last saved global options, or, if none
  280.     exist, to the internal default options of Amiga Oberon while the
  281.     operation mode is not changed.
  282.     
  283.   Read From... - pops a file requester and, if the name of a valid source
  284.     code module has been specified, imports the source code module's options
  285.     without changing the operation mode and the project name.
  286.     
  287.   Re-Read - re-reads the options from disk, i.e. for the Global operation
  288.     mode the last saved global compiler / linker options are imported, and
  289.     for the Project operation mode, the project's last saved compiler / 
  290.     linker are imported. This function is also known as 'Restore'.
  291.     
  292. Settings menu:    
  293.  
  294.   Create Icons? - if checked, OberonPrefs creates icons for projects
  295.     without icons when saving the project's compiler / linker options.
  296.     The icon data is taken from OBERON:Icons/txt.info, or if that does
  297.     not succeed, the system default project icon data is employed for
  298.     the job.
  299.     *1*
  300.     
  301.   Write Options That Default? - if checked, even those compiler /
  302.     linker options that correspond to the Oberon system's internal
  303.     default options are written. 
  304.     *1*
  305.     
  306.   Local Read submenu:  
  307.     The settings of this submenu determine how OberonPrefs proceeds
  308.     when reading a project's compiler / linker options. Firstly, the
  309.     user can choose one of four ways:
  310.     
  311.       Module & Prefs - if checked, OberonPrefs starts reading the options
  312.         from a possible OberonPrefs header line at the top of a source code
  313.         module: if char options preceeded by 'OberonOpts' / 'OLinkOpts' are
  314.         found within the header line, they are processed - the rest of the
  315.         header line is ignored for now. Then, OberonPrefs tries to override
  316.         these options with options read from Oberon.prefs resp. OLink.prefs
  317.         option preferences files. Finally, the rest of the the header line
  318.         is searched for valid source code options ($Option+, $Option-) which
  319.         override the hitherto gained settings.
  320.       
  321.       Module (No Option Chars) & Prefs - corresponds to checked 
  322.         'Module & Prefs', with the exception that the char options
  323.         preceeded by 'OberonOpts' / 'OLinkOpts' within an OberonPrefs
  324.         header line are ignored. As the Amiga Oberon system proceeds
  325.         like this when gathering options, This is the internal default
  326.         setting of OberonPrefs.
  327.         
  328.       Only Module - OberonPrefs only gathers options from OberonPrefs header
  329.         lines, including both, char options and source code options.
  330.          
  331.       Only Prefs - OberonPrefs only considers only Oberon.prefs /
  332.         OLink.prefs option preferences files.
  333.         
  334.     Moreover a toggle switch decides on the way Oberon.prefs / OLink.prefs
  335.     are gathered:
  336.     
  337.       Prefs: Fallback To Global? - if checked, OberonPrefs tries to open
  338.         the global option preferences files in the OBERON: directory if
  339.         it can't find them in the project's directory. This corresponds
  340.         to OberonPrefs internal default settings, as the Oberon system
  341.         proceeds in exactly the same way.
  342.         
  343.   Local Write submenu:      
  344.     The menu items of this submenu decide on the procedure OberonPrefs
  345.     applies for writing project's compiler / linker options.
  346.     *1*
  347.     
  348.       Stackable Opts As Source? - if checked, OberonPrefs writes those
  349.         options that may be changed via commandline char options, via
  350.         option preferences files and via source code options, as
  351.         source code options into the source code module's OberonPrefs 
  352.         header line. This was OberonPrefs' internal default setting up
  353.         to OberonPrefs1.9. Starting from OberonPrefs1.10 it is the
  354.         internal default setting of OberonPrefs to omit this.
  355.         *1*      
  356.  
  357.       Write Option Chars? - if checked, OberonPrefs writes the
  358.         char options for the compiler / linker invocation preceeded by
  359.         'OberonOpts' / 'OLinkOpts' into the OberonPrefs header line of
  360.         the source code module. This was OberonPrefs' internal default 
  361.         setting up to OberonPrefs1.9. Starting from OberonPrefs1.10 it
  362.         is the internal default setting of OberonPrefs to omit this.
  363.         *1*
  364.     
  365.     In addition to this, one of four different handlings for writing
  366.     option preferences files while saving a project's compiler / linker
  367.     options can be selected:
  368.     
  369.       Write *.Prefs With Options - makes OberonPrefs write the
  370.         option preferences files with the active compiler / linker
  371.         options into the project's directory. This is the internal
  372.         default setting of OberonPrefs.
  373.         *1*
  374.         
  375.       Write Empty *.Prefs - makes OberonPrefs write empty option
  376.         preferences files into the project's directory. This may be
  377.         useful if the Amiga Oberon system shall operate without
  378.         considering any options from preferences files.
  379.         *1*      
  380.         
  381.       Don't Write *.Prefs - causes OberonPrefs to ignore all option
  382.         preferences files and not to write any option preferences
  383.         files. This may be useful for changing only the options of
  384.         a specific source code module in a project directory without
  385.         touching the options of the other source code modules in the
  386.         same directory.
  387.         *1*
  388.         
  389.       Delete *.Prefs - makes OberonPrefs delete option preferences  
  390.         files present in the project's directory, and does not write
  391.         back any option preferences files.
  392.         *1*
  393.       
  394.     Finally you can set the mode for handling option ToolTypes in    
  395.     project icons while saving project options:
  396.     
  397.       Write ToolTypes - induces OberonPrefs to write the active
  398.         options as ToolTypes into the project icons. This was always
  399.         the case up to OberonPrefs 1.9. If an 'old' SETTINGS value
  400.         from OberonPrefs <= 1.9 is passed on program start or such
  401.         an old SETTINGS value is picked from the ENVARC:OberonPrefs.prefs
  402.         file, this is due to compatability considerations the default
  403.         setting for OberonPrefs1.10 or newer.
  404.         *1*  
  405.          
  406.       Ignore ToolTypes - makes OberonPrefs ignore any existing option
  407.         ToolTypes within project icons. Moreover OberonPrefs does not
  408.         modify any option ToolTypes. This is the normal internal default
  409.         setting of OberonPrefs starting from OberonPrefs1.10
  410.         *1*  
  411.         
  412.       Delete ToolTypes - causes OberonPrefs to delete existing option  
  413.         ToolTypes in project icons without writing any option ToolTypes
  414.         back into the icon.
  415.         *1*
  416.         
  417.   Save Settings - this menu item saves the current settings of the
  418.     Settings menu into the global ENVARC:OberonPrefs.prefs file so 
  419.     that the settings may be retrieved whenever OberonPrefs is
  420.     invoked later. (These settings are overridden by a specified
  421.     commandline / ToolType SETTINGS/N/K argument)
  422.     *1*
  423.  
  424.  
  425.     
  426. *1* :  Is not available if one of the arguments OBERONOUT, OLINKOUT or
  427.        OMAKEOUT has been specified at the program start.
  428.        
  429.  
  430.  
  431.               ---------------------------------------
  432.               dragging icons into OberonPrefs' window        
  433.               ---------------------------------------
  434.  
  435. You may drag icons into OberonPrefs' window.  This corresponds to
  436.   selecting the File gadget and specifying the icon's name in the
  437.   file requester.
  438.   *1*
  439.  
  440. *1* :  Is not available if one of the arguments OBERONOUT, OLINKOUT or
  441.        OMAKEOUT has been specified at the program start.
  442.        
  443.  
  444.  
  445.                     -----------------------------------
  446.                     commandline and ToolTypes arguments
  447.                     -----------------------------------
  448.  
  449. The following is OberonPrefs' argument stencil:
  450.  
  451. FROM,TO=FILE,OBERONOPTS/K,OLINKOPTS/K,EDIT/S,USE=SAVE/S,OBERONOUT/S,
  452. OLINKOUT/S,OMAKEOUT/S,GLOBAL/S,LOCAL/S,PUBSCREEN/K,NOGUI/S,NOSAVEGAD/S,
  453. SETTINGS/N/K,
  454. NoStackChk=S/S,NoOvflChk=V/S,NoRangeChk=B/S,NoCaseChk=C/S,NoReturnChk=R/S,
  455. NoNilChk=N/S,OddChk=O/S,NoTypeChk=T/S,SmallCode=M/S,SmallData=D/S,
  456. NoImplementation/S,NoGarbageCollector=A/S,NoExtensions=E/S,Debug=G/S,
  457. NoClearVars=Z/S,Icons=I/S,NoNewSymbols=Y/S,Small/S,mc68881=8/S,
  458. NoAutoRegPars=P/S,CodeChip/S,DataChip/S,VarsChip/S,mc68030=3/S,
  459. mc68020=2/S,mc68010=1/S
  460.  
  461.  
  462. Following now is a detailed description of each argument:
  463.  
  464. FROM - file name of the project whose compiler / linker options shall be
  465.   read. There are two special names, so called 'magics':
  466.     Global - reads the global compiler / linker options. (This is also
  467.       the case if this argument is neglected)
  468.     Default - sets the internal default options of the Amiga Oberon
  469.       system.       
  470.     The specification of the switches LOCAL/S or USE=SAVE/S have the effect
  471.     that in case the TO=FILE argument is not passed and in case the FROM
  472.     argument is no 'magic', the FROM arguemnt is used as the TO=FILE arg.
  473.     
  474. TO=FILE - file name of the project that shall be processed. The
  475.   specification of this argument implies the LOCAL/S switch and
  476.   excludes the specification of the GLOBAL/S switch.
  477.   
  478. OBERONOPTS/K,OLINKOPTS/K - see below
  479.  
  480. EDIT/S - switch that makes OberonPrefs operate in the interactive mode.
  481.   Since this is the internal default setting of OberonPrefs, you can
  482.   always omit this switch. The explicit specification of EDIT/S excludes
  483.   the usage of the USE=SAVE/S and NOGUI/S switches.
  484.   
  485. USE=SAVE/S - switch that causes OberonPrefs to save the gathered compiler /  
  486.   linker options without opening the interactive graphical user interface.
  487.   This switch excludes the usage of EDIT/S, and assumes that an existing,
  488.   valid project name has been passed as TO=FILE argument (that may stem
  489.   from the FROM argument, see above for more) if the Project operation
  490.   mode is active.
  491.   
  492. OBERONOUT/S  
  493. OLINKOUT/S
  494. OMAKEOUT/S  - these switches are mutually exclusive and have the effect
  495.   that in case of non-failure termination the commandline option string
  496.   with the option chars for Oberon / OLink / OMake is printed to the
  497.   standard output chanel. These arguments are utterly important for
  498.   OberonPrefs' utilization in batch files and ARexx scripts.
  499.   The interactive graphical user interface of OberonPrefs is heavily
  500.   modified by the specification of one of these arguments:
  501.     It isn't possible to toggle the operation mode (Global / Project),
  502.     and you can't process any other project than the one passed on
  503.     startup. The Settings menu is heavily pruned: only the Local Read
  504.     submenu is left. Instead of the Cancel gadget, a Use gadget is
  505.     displayed (You can still access the Cancel operation by triggering
  506.     the window's close gadget or by selecting the Project->Quit menu
  507.     item), or, if the NOSAVEGAD/S switch is active, the Save gadget is
  508.     replaced by the Use gadget. In this case, the Save function can't
  509.     be accessed at all.
  510.     
  511. GLOBAL/S - This switch activates the Global operation mode (which is    
  512.   OberonPrefs' internal default). This excludes the specification of
  513.   the TO=FILE and LOCAL/S arguments.
  514.   
  515. LOCAL/S - This switch activates the Project operation mode. Thus, you  
  516.   can't use the GLOBAL/S switch, of course. This switch is automatically
  517.   activated if a non-magic FROM argument in connection with the
  518.   USE=SAVE/S switch or simply a TO=FILE argument have been passed.
  519.   
  520. PUBSCREEN/K - Here you can specify the name of a public screen on wich  
  521.   OberonPrefs should open its interactive graphical user interface.
  522.   If the screen can't be found, a fallback to the system default public
  523.   screen (which is OberonPrefs' internal default setting) takes place.
  524.   
  525. NOGUI/S - This switch is only reasonable in conjunction with one of
  526.   the switches OBERONOUT/S, OLINKOUT/S or OMAKEOUT/S. It has the effect
  527.   that the interactive graphical user interface is not opened despite an 
  528.   inactive USE=SAVE/S switch. Instead of that, the respective compiler / 
  529.   linker options are read, and printed to the standard output chanel
  530.   according to the specified #?OUT/S switch. The specification of this
  531.   switch is also allowed (but without any effect) in conjunction with
  532.   the USE=SAVE/S switch.
  533.   
  534. NOSAVEGAD/S - This witch is only permitted in conjunction with a #?OUT/S  
  535.   switch and an opened interactive graphical user interface. For a 
  536.   detailed description of its effects, see the discussion of the #?OUT/S
  537.   switches.
  538.   
  539. SETTINGS/N/K - This argument expects a valid decimal number which  
  540.   decodes to valid settings of the Settings menu's options.
  541.     The desired number can be easily found by modifying the Settings
  542.     menu's options and selecting the Project->About... menu item
  543.     afterwards. In the last text line of the information requester
  544.     that pops up, the current settings number can be found.
  545.     *1*
  546.     
  547.     
  548. The remaining arguments have the purpose to activate / clear one or more
  549. of the compiler / linker options:
  550.  
  551. OBERONOPTS/K - expects the specification of a valid option string for
  552.   the Oberon compiler, consisting of an optional '-', followed by the
  553.   option chars.
  554.   
  555. OLINKOPTS/K - expects the specification of a valid option string for
  556.   the OLink linker, consisting of an optional '-', followed by the
  557.   option chars.
  558.   
  559. NoStackChk=S/S,NoOvflChk=V/S,NoRangeChk=B/S,NoCaseChk=C/S,NoReturnChk=R/S,
  560. NoNilChk=N/S,OddChk=O/S,NoTypeChk=T/S,SmallCode=M/S,SmallData=D/S,
  561. NoImplementation/S,NoGarbageCollector=A/S,NoExtensions=E/S,Debug=G/S,
  562. NoClearVars=Z/S,Icons=I/S,NoNewSymbols=Y/S,Small/S,mc68881=8/S,
  563. NoAutoRegPars=P/S,CodeChip/S,DataChip/S,VarsChip/S,mc68030=3/S,
  564. mc68020=2/S,mc68010=1/S - sets / clears a particular option.
  565.  
  566.  
  567.  
  568. *1* :  Is not available if one of the arguments OBERONOUT, OLINKOUT or
  569.        OMAKEOUT has been specified at the program start.
  570.        
  571.   
  572.   
  573.      user definable interactive argument request on Workbench start  
  574.      --------------------------------------------------------------  
  575.  
  576. OberonPrefs provides you with the ability to gather specific, several, or
  577. all arguments with interactive argument string requesters if it is started
  578. from Workbench and you have installed reqtools.library V38 or higher (which
  579. is copyright by Nico François, by the way) in your system. In order to make
  580. OberonPrefs do this, you have to create valid ToolType entries, with a
  581. preceeding 'ASK:' prefix, e.g. 'Ask:Settings=971' and so on.
  582.  
  583.  
  584.  
  585.                     program termination & return codes
  586.                     ----------------------------------
  587.  
  588. If OberonPrefs is quit using either the Save gadget, the Use gadget or
  589. by pressing the corresponding key equivalents, it returns a return code
  590. of 0 (OK). If the graphical user interface is not opened due to the
  591. supplied arguments, and OberonPrefs terminates properly, it returns 0
  592. (OK), too.  Otherwise, if OberonPrefs terminates due to the Project->Quit
  593. menu item, the windows's close gadget, due to presssing ESC, due to the
  594. Cancel gadget or its key equivalent, it returns 5 (WARN). In all other
  595. cases - i.e. whenever OberonPrefs terminates because of invalid arguments
  596. or insufficient system resources, it returns 20 (FAIL), and if not one
  597. of the #?OUT/S switches was specified, it prints a failure message to the
  598. standard output chanel and flashes the screen in case it was started from
  599. Workbench.
  600.  
  601.  
  602.  
  603.  
  604.                      general issues about the program
  605.                      --------------------------------
  606.  
  607. Valid projects for OberonPrefs are existing text files whose name end
  608. with a '.mod' suffix. OberonPrefs has, like the other Oberon system's
  609. tools the ability to automatically append the '.mod' to any specified
  610. file name, and to look also in a 'txt' sub-directory for the file if
  611. the file could not be found in the specified directory.
  612.  
  613.  
  614. The CodeChip+, DataChip+, VarsChip+ and Implementation- settings are 
  615. volatile for the Global operation mode since they can be only specified
  616. within source code modules, i.e. they can't be saved as the global
  617. compiler / linker options. Thus, if you convert a project's compiler /
  618. linker options into the global compiler / linker options, or if you read
  619. project options only emloying the *.prefs option preferences files,
  620. those settings are lost.
  621.  
  622.  
  623. A small note on the used ToolTypes parsing:  The unique ToolTypes parsing
  624. functions of BlackMagic which support the AmigaDOS-ReadArgs()
  625. templates extensively, and also offer the nifty 'Arguments Request'
  626. feature (see above for more) are used.
  627.  
  628.  
  629.                    -------------------------------------
  630.                    how to avoid source code modification
  631.                    -------------------------------------
  632.                    
  633. If you want to avoid the creation of OPREFS header lines on the
  634. long run, you should deselect the menu toggles
  635.  
  636. * Settings->Save·Options·That·Default?
  637.  
  638. and
  639.  
  640. * Settings->Local·Write->Stackable·Opts·As·Source?
  641.  
  642. and
  643.  
  644. * Settings->Local·Write->Write·Option·Chars?
  645.  
  646.  
  647. and save these settings with the menu item 
  648.  
  649. *Settings->Save·Settings
  650.  
  651.  
  652.           * Starting from OberonPrefs 1.10 these settings are *
  653.           * the  internal  default  settings  of  OberonPrefs *
  654.   
  655.  
  656.  
  657.                               program history
  658.                               ---------------
  659.  
  660.   v1.0 [fSchwarz] 28.6.93  First fully functional version
  661.  
  662.   v1.1 [fSchwarz] 4.7.93  Removed stupid bug in argument
  663.     processing order: processed SETTINGS after FROM & TO
  664.  
  665.   v1.2 [fSchwarz] 6.7.93  Added display clip sensitivity
  666.     when rendering x/y positions, pr.windowPtr redirection
  667.  
  668.   v1.3 [fSchwarz] 6.7.93  Added warning requester for
  669.     filenames not ending in '.mod', changed requester code
  670.  
  671.   v1.4 [fSchwarz] 9.7.93  Added 'OberonPrefs failed' msg &
  672.     Int.DisplayBeep() in case of failure, Dos.IoErr support
  673.  
  674.   v1.5 [fSchwarz] 16.7.93  Fixed Asl.save-Flag FReq bug
  675.  
  676.   v1.6 [fSchwarz] 17.7.93  Removed ~'.mod' warn requester,
  677.     adapted filename handling to Oberon's (add missing
  678.     '.mod' suffix, search in 'txt' subdirectory)
  679.  
  680.   v1.7 [fSchwarz] 21.7.93  Adapted to new BlackMagic layout
  681.  
  682.   v1.8 [fSchwarz] 14.8.93  Recompiled with BlackMagic 1.10:
  683.     now argument requesters may pop up if wbstarted
  684.  
  685.   v1.9 [fSchwarz] 9.9.93  fixed mc680x0 option management
  686.     due to very strange compiler feature: Enabling 68030
  687.     instruction generation does NOT imply generation of
  688.     68020/68010 instructions, etc.
  689.  
  690.   v1.10 [fSchwarz] 10.9.93  Added user control of Project-
  691.     ToolTypes writing via Settings menu; changed default
  692.     settings so that usually no source writes are needed.
  693.  
  694.   v1.11 [fSchwarz] 13.9.93  Minor cosmetic code changes,
  695.     now works well with a NIL Asl.base, added
  696.     complete English docs, corrected German docs, updated
  697.     strings.
  698.  
  699.   v1.11a [fSchwarz] 17.9.93 Added Busypointer & window
  700.     blocking during writing / reading operations (suggested
  701.     by Christian Stiens)
  702.  
  703.   v1.11b [fSchwarz] 18.9.93 now also locked GUI during
  704.     ValidateFName() due to packing filesys like XFH, etc.
  705.  
  706.   v1.11c [fSchwarz] 18.9.93 DisplayBeeps if ValidateFName()
  707.     fails in interactive mode.
  708.  
  709.   v1.11d [fSchwarz] 20.9.93 Now writes OLink.prefs options
  710.     in complete upper case.
  711.  
  712.  
  713.  
  714.                                 final notes
  715.                                 -----------
  716.  
  717. The complete source code of OberonPrefs can be ordered by 
  718. contacting the author.  The source code of the old version 
  719. OberonPrefs1.7 can be found on disk #91 of the Amok disk 
  720. library.
  721.  
  722.  
  723. Known Bugs: Currently, no known bugs exist. However, due to the
  724. enormous extent of this project, it is possible that a few bugs
  725. are in the code that haven't turned out yet.
  726.  
  727.  
  728. OberonPrefs is Giftware. In other words, I strongly encourage you to
  729. send me a small present, a donation, a nice posccard, and so on, if
  730. you appreciate this program and you use it.
  731. Suggestions, comments, bug reports, criticism, praise, etc.  are
  732. welcomed, too!
  733.  
  734. If you want to translate this documentation into other languages, feel 
  735. free to do so, add the translation to this archive, and send them to the
  736. author (that is me;-)) The same goes for catalog files, too!
  737.  
  738.  
  739. OberonPrefs is copyrighted and protected by copyright laws all over
  740. the world. Copyright © 1993 Franz Schwarz.
  741.  
  742.  
  743. The author can't be hold liable for any harm that stems from the
  744. usage of this program, no matter whether direct harm or indirect harm.
  745.  
  746. OberonPrefs is freely distributable; it may be published in the Amok
  747. software collection and in other non-commercial software collections,
  748. including CD-ROM versions of them. Moreover, it may be spread via
  749. electronic data transfer.
  750.  
  751. OberonPrefs may only be distributed in this archive as a whole.  It may 
  752. be only distributed if the distributor does not claim any copyright on
  753. the OberonPrefs archive nor on any files that are compulsorily distributed
  754. with it. Inquiries on exceptions from these limitations may be submitted
  755. to the author.
  756.  
  757.  
  758.                            contacting the author
  759.                            ---------------------
  760.  
  761.                                Franz Schwarz
  762.                               Mühlenstraße 2
  763.                        D-78591 Durchhausen, Germany
  764.                     Uucp: Franz_Schwarz@mil.ka.sub.org
  765.                     Fido: 2:2476/506.18 & 2:241/7506.18
  766.                          Bank account 951.207 at 
  767.              KSK Trossingen, Germany, bank ZIP code 643 500 70
  768.  
  769.  
  770.  
  771.  
  772.                                   Credits
  773.                                   -------
  774.  
  775. The interactive graphical user interface was created with assistance of
  776. GadToolsBox 37.176 by Jan van der Baard und Kai Bolay (Oberon source
  777. generator).  Without GadToolsBox, OberonPrefs would have hardly ever been
  778. realized. Three galactic Gargle Blaster cheers for them;-)
  779. The CygnusEd ARexx scripts use Kai Bolay's oberonsupport.library, and
  780. some parts of the ARexx scripts are also written by him.
  781. The reqtools.library, OberonPrefs can take advantage of, is written and
  782. copyrighted by Nico François, but freely distributable if this fact
  783. is mentioned in the accompanying program documentation.
  784.  
  785.  
  786. Have fun,
  787.  
  788. Franz 'Blacky' Schwarz
  789.  
  790.                - Girlfriend Is Better - Talking Heads -
  791.  
  792.  
  793.                         the CygnusEd Arexx scripts
  794.                         --------------------------
  795.  
  796. The CyngusEd ARexx scripts provide you with a comfortable interface of
  797. CygnusEd Professional to your Oberon system.  The following brief
  798. introduction assumes that the enclosed function key mapping of CygnusEd is
  799. activated.
  800.  
  801. F1 - Compile: Invokes the compiler. If the module has been modified and it
  802.   is unsaved yet, it is saved right before compilation. The first compiler
  803.   error is displayed after compiling if errors occured.
  804.   
  805. F2 - Link: Invokes the linker
  806.  
  807. F3 - Make: Invokes the OMake make utility. If the module has been modified
  808.   and it is unsaved yet, it is saved right before invoking OMake.
  809.  
  810.  
  811. Compile, Link and OMake use the following compiler / linker options:
  812.   if valid temporary options for the project exist from a former 
  813.   'F7 - Change Temporary Options' invocation, those are used. Otherwise
  814.   the options are gained by invoking OberonPrefs with activated 
  815.   'Settings->Local Read->Module & Prefs' and
  816.   'Settings->Local Read->Prefs: Fallback to Global?'' menu items.
  817.   
  818. F4 - First Error: Jumps to the first compiler error
  819.  
  820. F5 - Next Error: Jumps to the next error relative to the cursor
  821.  
  822. F6 - Prev. Error: Jumps to the previous error relative to the cursor
  823.  
  824. F7 - Change Temporary Options: Set / invalidate temporary options for
  825.   a source code module. If the module has been modified and it is
  826.   unsaved yet, it is saved right before the OberonPrefs invocation.
  827.   
  828. F8 - Change Options: Unrestricted manipulation of compiler / linker  
  829.   options of arbitrary projects and of the global options using
  830.   OberonPrefs. If the currently edited text is an oberon source
  831.   code module that has been changed and which is unsaved yet, it
  832.   is saved right before the invocation of OberonPrefs. If you changed
  833.   the options of the currently edited module, you should re-open
  834.   the mdoule with the CygnusEd menu item Project->Open... after 
  835.   quitting OberonPrefs.
  836.   
  837.   
  838. If you use the ARexx scripts regularly, I recommend making OberonPrefs
  839. resident by invoking 'resident OBERON:OberonPrefs'
  840.  
  841.  
  842. For detailed information on the ARexx scripts, have a look at the scripts
  843. themselves.
  844.  
  845.  
  846.  
  847.       Bye,
  848.         Franz 'Blacky' Schwarz
  849.  
  850.                - Girlfriend Is Better - Talking Heads -
  851.  
  852.  
  853.